FishMarket 1.0/FishMarket v1.0.iso/fishies/351-375/disk_369/aqdata/aquadoc

Text File | 1992-05-06 | 12KB | 225 lines

    The following is information provided for those wishing to update and
    maintain the Aquarium V1.12 data base files.  Aquarium and NewFish are
    programs from Disk 301 submitted to the AmigaLib Disk collection by
    B Lennart Olsson.  The programs are copyright 1989, however, they are
    redistributable when the Aquarium.DOC file (copyright header prepended)
    is included in the distribution.  See AmigaLib Disk 301 documentation
    for details.

    This document has a short description of the Aquarium V1.12 data base.
    The data base is in the Aquarium directory "data", and consists of just
    four files (not including the .info file), all of which are described
    below.

    KeyNames

    The KeyNames file contains the text which will appear in the search
    key subwindows upon running the Aquarium program.  The file has 30 or
    more lines.  The file is a completely ASCII readable file, which is
    easily edited or repaired (if you have even a remotely recent copy and
    a fair memory).  The file has its own documentation (beyond line 30).
    Only the first 15 characters of each of the first 30 lines are used by
    the Aquarium program for initialization of the subwindows.  Changing
    the meaning of any of these keys will in concert require working over
    the entire database one fish at a time to therein set or reset the key
    in accordance with the newly assigned meaning for each changed key.
    This update has utilized the formerly one remaining empty key, giving
    it the title "Enhancements".  All of the programs in the data base that
    have Contents files which mention ARP or Rexx have been thus tagged.
    I hope you are not inconvenienced by this; it should help most users
    in tracking FD software support for these important Amiga enhancements.

    Names

    The Names file contains one 20-byte record for each item in the index,
    where an item is defined by one left-justified entry in a README.list
    or Contents file from an AmigaLib Disk.  However, there are instances
    where the contents of an entire disk is entered as a generalized item,
    such as "Disk#_64".  With such global names excepted, the consecutive
    printable characters in the item name are followed by spaces, with a
    null terminator as the last character.  The characters of a properly
    installed global name are followed immediately by a null character with
    spaces up to the last character; again, the last character is a null
    terminator.  Spaces are not allowed within names.  Note that the update
    program included in the Aquarium distribution (NewFish V1.03 (c) 1988
    B Lennart Olsson) will not produces global names with this interminary
    null character; however, the character can be easily produced whenever
    necessary by means of a binary file editor such as NewZap.

    Two examples are shown below (note that the spacing count is crucial):

        Disk#_64\000         \000
        Aquarium           \000

    The data base in this update has 1836 names; these names are referenced
    as "fish" in the Aquarium.  Those maintaining their own data base will
    have 1846 names if they are current to Disk 360.  This data base is
    changed in the following ways:

        Disk 57 was withdrawn due to copyright problems. It was then
         re-issued as Disk 97.  The six entries in the V1.12 Aquarium
         data base attributable to Disk 57 have thus been removed, and
         a retraction notice, such as was already in the data base for
         Disk 80, was substituted.

        Six other items were removed from the data base, one each for
         Disks 173, 221, 230, 238, 305, and 324 as these items have
         been withdrawn from distribution (other items on the disks
         that are yet in the catalog will be available on these same
         disk numbers, but re-issued with an "a" appended to the disk
         name).  The Aquarium program (Ver 1.12) knows nothing of "a"
         disk name extensions, but no matter, only a volume number is
         needed in order to examine the currently available contents
         of these disks in this data base.

        Disk 176, formerly named "Disk#_176" featured an early release
         of "AnalytiCalc" and a construct titled "Hypertext."  In this
         data base they are separately named, resulting in the creation
         of an additional item - thus an additional "fish" entry.

        Several global entries with multiple null trailers (linefeeds
         in Aquarium's printing operations) were changed to conform to
         the space-separated two-null global format described above.


    index

    The index file is the most important file in the data base.  If the
    index is damaged, the database will be difficult to repair.  As Lennart
    suggests, always preserve a copy of the data base files before using
    the NewFish program or before working on the files with binary file
    editors.  The index file consists of sequential 14 byte records, as
    many records as there are items (fish) in the data base.  The meaning
    assigned to the bits in each index item record is described next.

    The appearance of a short group of records near the end of this update
    of the index is shown below:

        A  B  C  D  E  F  G  H  I  J  K  L  M  N

        00 04 34 a0 01 5c 00 08 2d 49 01 61 00 00
        04 00 06 b0 01 5d 00 08 2e aa 02 44 00 00
        04 40 80 04 01 5e 00 08 30 ee 00 b2 00 00
        00 42 12 15 01 5e 00 08 31 a0 00 ef 00 00
        00 20 14 04 01 5e 00 08 32 8f 01 b9 00 00
        08 00 02 38 01 5e 00 08 34 48 01 af 00 00
        00 00 16 10 01 5f 00 08 35 f7 02 5e 00 00
        00 80 16 12 01 60 00 08 38 55 01 4b 00 00

    The one-byte wide columns have the following assigned content:

        A through D    Keys    Show  which of 30 search keys are set.
        E through F    Disk    AmigaLib Disk number
        G through J    ItemAdr Absolute addrs of data file item texts.
        K through L    ItemSiz Contents record size including trailer.
        M through N    Delim    Record separator bytes (null).

    The Aquarium window has a rectangular area containing 30 search key
    subwindows.  Each search key is assigned one bit of the first longword
    of the record.  The two MSBs (lefthand bits) are always zero, and the
    others are set by the user via mouse selects in the red "keys" window.
    The top leftmost search key is the rightmost bit (LSB) of the longword.
    The top next-to-leftmost search item (row 1, column 2) is the 2nd LSB,
    and the sixth LSB is again back to the leftmost column next-to-the-top
    row (row 2, column 1).

    The ItemAdr is the absolute address of the first byte of the Contents
    file record in the file "data".  It is this construct that makes the
    Aquarium data base a quickly readable structure, but it does so at the
    cost of serious inflexibility in so far as insert/delete operations are
    concerned.  To insert or delete an item requires recalculation of all
    of the following absolute Contents record addresses.  A phase error
    between the index file and the data file will result in a "graceful"
    termination of the Aquarium program execution and a return of program
    resources to the AmigaDOS Exec on exit.

    data

    This is a variable-length record file which contains the concatenated
    AmigaLib Disk README.list and Contents files.  The text of each file
    consists of lines of characters, each with one null terminator.  The
    field separator between files is a 56 null character string.  The char
    count in the separator must be 56 null characters.  The separator field
    appears as a 57 null character group when the data file is perused with
    a binary editor, owing to the seeming inclusion of the null character
    that terminates the last line of the file.  As explained above, the
    index file contains address pointers to the first readable character
    of each item, and contains a size value for each item including the
    item separator.  The data file is easily edited with a binary file
    editor such as NewZap.  Usually, but quite definitely not always, the
    last line of a Contents file has the names of the contributors, i.e.,

        Author: Gill Green and Dorsal Fin

    This update of the data base contains several minor modifications to
    the Contents files found in the original Aquarium release.  The bases
    track fairly well up to about AmigaLib Disk 163, but then for some
    reason there were lots of entries that were different by a few bytes.
    Examination of the two data base files revealed that either Lennart
    has a Contents file processor that, among other things, trims spaces
    at the ends of lines (as are on occasion found in the Contents files
    of the AmigaLib disks sent to my by Fred), or Lennart's disks are
    different from the ones I have.  Lennart does recommend copying the
    Contents files from disks that are to be appended to the data base,
    and editing them for form.  This will help to head off an inappropriate
    entry now and then.  For my part I ran into various problems in this
    regard, ranging from free-format README.list files which did not have
    separated items, European characters embedded in Author names (these
    cause truncation - see Disk 19 or Disk 163 for example), and failure
    to eliminate blank lines in Contents items when constructing the file
    manually. (This is an error I would make now and then.)  I know I did
    a lot of incidental correction, such as adding the name of Bill Nelson
    to the otherwise blank Author field on AmigaLib Disk 237 (CType entry).

    Truncating the data base

    As careful as you may be in adding new fish to the Aquarium, the time
    will likely come when you will either enter a poorly formed Contents
    file, or will abort during the entry.  When this occurs, it will be
    necessary to truncate the data base.  The description above will allow
    you do this via the knowledge of just where it is you must cleave the
    forms.  If you were caught in the middle of adding a new disk, you must
    truncate back to the previous disk number (examine columns E and F of
    the index.)  A truncated Names file size must be an integral product of
    20 bytes times the number of records, and the index file size must be
    an integral product of 14 bytes times the same number of records.

    The data base provided here has 1836 records per data base file, except
    of course, the KeyNames file.  The truncation may be accomplished with
    a disk editor (DiskX, Sec, etc.), or you may wish to use the FileMaster
    program on AmigaLib Disk 298, which has the ability to do binary edits
    and to shorten as well as lengthen files.  If the data base should be
    corrupted, you are in for heavy duty work on the index file once the
    data file is corrected because of the need to recalculate some several
    hundered absolute data pointers.  It would seem an easy task to write
    a stdio filter program to do this, though, would it not?  Another way
    to get this out would be to utilize the assembly language guts of the
    DezHexBin program on AmigLib Disk 321 to make an appropriate filter.

    Other Maintenance Items

    Included in this kit is a list of all of the README.list/Contents
    files I found necessary to change in order to deal with the data base.
    The file READMElist has these files listed all as README.list###
    files since as Contents files they would be indistinguishable from
    each another when it comes to placement in a directory for reference.

    Bugs

    The Aquarium program itself is seemingly bug free.  However, as Lennart
    himself admits, the NewFish program is rather touchy.  If possible, use
    NewFish from a Non-Interlaced workbench CLI.  If you use interlace, you
    will likely experience loss of all of the screen icons upon exit.
    There will not likely be any permanent damage to anything as a result
    of the condition which comes along with this situation; I have never
    had any data base file or icon file destruction as a result of it, and
    it does not cause the machine to crash (at least not right away).  This
    may only be a problem with Aquarium V1.12 in the AmigaDOS environment,
    and may be found to have been remedied in future versions - I suppose
    you'll have to speak with Lennart if you want help on this one.